Node / ReticulumProjects / MeshChatX.git / files / docs / agents / conventions / backend.md

Displaying Raw • View rendered • Download

Tc9d1d9# Backend conventions

Applies when editing Ta5d6ff`meshchatx/**/*.py`.

Tff7b72- Prefer Ta5d6ff`uv run` / Ta5d6ff`task` for pytest and ruff.

Tff7b72- HTTP handlers: return 400 for Ta5d6ff`ValueError` / bad input, 503 for retryable SQLite/Landlock unavailability, 500 only for unexpected failures.

Tff7b72- Thin HTTP handlers live under Ta5d6ff`meshchatx/src/backend/http/routes/`. Parse the request, call a manager or app method, map errors. Do not add new business logic in route modules.

Tff7b72- Shared HTTP helpers: Ta5d6ff`backend/http/errors.py`, Ta5d6ff`backend/http/context.py`, Ta5d6ff`backend/http/middleware.py`, Ta5d6ff`backend/http/register.py`, Ta5d6ff`backend/http/live_names.py`.

Tff7b72- Ta5d6ff`errors.py` and Ta5d6ff`context.py` are intentional scaffolding. Adopt Ta5d6ff`http_bad_request` / Ta5d6ff`http_unavailable` / Ta5d6ff`http_unexpected` only when a handler is already thin. Do not refactor fat handlers only to call them.

Tff7b72- When splitting or moving handlers among Ta5d6ff`routes/<domain>.py`, follow Ta5d6ff`docs/agents/skills/meshchat-orchestration-split/SKILL.md` and Ta5d6ff`docs/agents/module-ownership.md`. Mechanical moves only (no behaviour change in the same change).

Tff7b72- Multipart parsers must not assume field order.

Tff7b72- SQLite worker connections must set Ta5d6ff`temp_store=MEMORY` in Ta5d6ff`DatabaseProvider` (Landlock-safe).

Tff7b72- Under Landlock, memory-pressure must not force FILE temp for conversation queries.

Tff7b72- Keep conversation list queries slim: truncate content, derive attachment flags in SQL, avoid shipping full Ta5d6ff`fields` blobs.

Tff7b72- Identity restore validates size and empty payloads. Preserve existing identity metadata on re-import.

Tff7b72- No backticks in code comments. Prefer plain words or quoted identifiers.

Tff7b72- RRC / LXMF / LXST changes: open the matching skill under Ta5d6ff`docs/agents/skills/` and run oracle-style tests when behaviour changes.

Tff7b72- Local filesystem browse/upload/download/delete: follow Ta5d6ff`docs/agents/conventions/path-jail.md` and Ta5d6ff`docs/agents/skills/path-jail-local-fs/SKILL.md`.